Add CLAUDE.md guide and pixel game hub launcher by blackboxprogramming · Pull Request #21 · BlackRoad-OS/.github

blackboxprogramming · 2026-02-04T00:00:34Z

Summary

This PR establishes the foundational documentation and interactive UI for the BlackRoad OS Bridge repository. It introduces CLAUDE.md as the central AI assistant guide and creates a polished game hub launcher for the pixel worlds ecosystem.

Key Changes

CLAUDE.md - Comprehensive 244-line guide for AI assistants covering:
- Repository purpose and structure (15-org ecosystem, routing thesis)
- Complete directory map with all subdirectories and files
- Naming conventions, coding style, and design system specifications
- Development workflows for games, orgs, and prototypes
- AI decision authority framework (FULL_AUTO/SUGGEST/ASK_FIRST)
- Infrastructure summary and quick commands
blackroad-pixel/games/index.html - Interactive game hub featuring:
- Starfield background with twinkling animation
- 4-game grid layout (responsive, 2-col desktop / 1-col mobile)
- Individual game cards with:
  - Thematic preview backgrounds (farm, space, pink, platformer)
  - Game-specific badges (FARM SIM, PIXEL RPG, VIRTUAL PET, PLATFORMER)
  - Feature descriptions and tag lists
  - Hover animations and color-coded play buttons
- BlackRoad brand gradient bars and Press Start 2P typography
- Links to stardew/, pokemon/, webkinz/, and mario/ game directories

Implementation Details

Design System: Consistent use of BlackRoad color palette (#ff6b9d, #c44dff, #00d4ff, #7ed321, #f5a623)
Accessibility: Semantic HTML, proper contrast ratios, mobile viewport meta tag
Performance: Single-file HTML with embedded CSS/JS (no external dependencies except Google Fonts)
Navigation: Back link to desktop, footer with copyright and links
Theming: Dark theme (#050510 bg) with animated starfield, BEM-like CSS class naming

Notes

CLAUDE.md serves as the "Rosetta Stone" for understanding the entire Bridge repository structure
Game hub is fully self-contained and can be served from any static host
All 4 game worlds (Harvest, Creatures, Pets, Runner) are now discoverable from a single entry point

https://claude.ai/code/session_016tjFc6t2emynRTw5Mbi9Y9

- BlackRoad Harvest: Stardew Valley-inspired farming sim with crops, seasons, shop, day/night cycle - BlackRoad Creatures: Pokemon-inspired RPG with 8 creatures, battles, type matchups, capture, leveling - BlackRoad Pets: Webkinz-inspired virtual pet world with 6 pets, 5 rooms, minigame, shop, decor - BlackRoad Runner: Mario-inspired platformer with 3 worlds, physics, enemies, power-ups, coins - Game hub launcher page linking all worlds - Comprehensive CLAUDE.md documenting repo structure, conventions, and workflows https://claude.ai/code/session_016tjFc6t2emynRTw5Mbi9Y9

https://claude.ai/code/session_016tjFc6t2emynRTw5Mbi9Y9

Creatures (Pokemon): Expanded to 50x40 overworld with 5 zones, healing center, Pokedex, 3 trainer battles, item shop, PP system, critical hits, smart AI, zone-specific encounter tables, and level-up animations. Harvest (Stardew): Added weather system (rain/storm/snow), 4 NPCs with relationship/gifting, fishing minigame with 4 fish types, animals (chickens/cows), crop quality system, particle effects, fireflies, and expanded 30x22 world. https://claude.ai/code/session_016tjFc6t2emynRTw5Mbi9Y9

Pets (Webkinz): Added friendship/level system (1-10), pet naming, 3 minigames (Catch Treats with combos, Memory Match, Rhythm Tap), dress-up system with accessories, Adventure Room for exploration, 10+ achievements, enhanced pet AI with mood emotes, daily login bonus, wallpapers, and more shop items. Runner (Mario): Expanded to 5 worlds including Ice World and Castle/Boss. Added fire flower power-up with fireball shooting, piranha plants, flying goombas, bullet bills, boss fight, moving platforms, variable jump height, coyote time, sprint, checkpoints, pipe warps to bonus rooms, 3-layer parallax scrolling, and chain stomp score multipliers. https://claude.ai/code/session_016tjFc6t2emynRTw5Mbi9Y9

blackroad-pixel/games/mario/index.html

+
+function showBanner(text) {
+  const banner = document.getElementById('level-banner');
+  banner.innerHTML = text.replace('\n', '<br>');


To fix the problem, we should ensure that every newline character in text is converted to an HTML line break, not just the first one. The idiomatic way in JavaScript is to use a regular expression with the global flag: text.replace(/\n/g, '<br>'). This addresses the specific CodeQL concern about only the first occurrence being replaced.

The best minimal fix, without changing behavior otherwise, is to modify line 2039 in blackroad-pixel/games/mario/index.html so that text.replace('\n', '<br>') becomes text.replace(/\n/g, '<br>'). No additional imports or helper methods are needed, and the function’s external interface stays the same—only the handling of multiple newlines is improved. This change is fully contained within the showBanner function and does not affect other code.

chatgpt-codex-connector · 2026-02-27T18:10:26Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

Copilot

Pull request overview

Adds foundational repo guidance and a new “Pixel Worlds” game hub experience inside blackroad-pixel, linking the desktop UI to multiple self-contained HTML5 canvas games.

Changes:

Introduces CLAUDE.md as a central AI assistant / repo guide with structure, conventions, and workflows.
Adds a blackroad-pixel/games/index.html launcher (game hub) and links it from the desktop navigation.
Adds large, self-contained game pages for Stardew-like farming, Pokémon-like RPG, and Webkinz-like virtual pets.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`CLAUDE.md`	Adds a comprehensive repo guide (structure, conventions, commands).
`blackroad-pixel/index.html`	Adds a “Games” navigation link to the new hub.
`blackroad-pixel/games/index.html`	Implements the game hub/launcher UI and links into game directories.
`blackroad-pixel/games/stardew/index.html`	Adds the “BlackRoad Harvest” farming sim (canvas-based).
`blackroad-pixel/games/pokemon/index.html`	Adds the “BlackRoad Creatures” RPG/battle/capture game (canvas-based).
`blackroad-pixel/games/webkinz/index.html`	Adds the “BlackRoad Pets” virtual pet world + minigames (canvas-based).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-27T18:10:29Z

CLAUDE.md

+## Repository Structure
+
+```
+.github/


The repository structure diagram shows .github/ as the repo root, but this repository already contains a real .github/ directory (for workflows). As written, the tree implies paths like .github/.github/workflows, which is misleading for contributors. Consider using ./ as the root in the diagram (or clarifying that .github/ is the repo name, not a directory).

Suggested change

.github/

./ # Repo root (BlackRoad-OS/.github)

Copilot · 2026-02-27T18:10:30Z

blackroad-pixel/games/stardew/index.html

+  {id:'cyber_trout',name:'Cyber Trout',icon:'\uD83D\uDC1F',value:120,difficulty:0.22,color:'#ff6b9d'},
+  {id:'golden_byte',name:'Golden Byte',icon:'\uD83D\uDC1F',value:200,difficulty:0.12,color:'#f5a623'}
+];
+


fishTypes uses difficulty values as cumulative probabilities, but the values sum to 1.04 (0.4 + 0.3 + 0.22 + 0.12), which skews the intended spawn rates (the last fish will be under-selected). Either normalize these to sum to 1.0 or switch to a weight-based selection (roll against the sum of weights).

Suggested change

// Normalize fish difficulties so they form a proper probability distribution

const totalFishDifficulty = fishTypes.reduce((sum, fish) => sum + fish.difficulty, 0);

if (totalFishDifficulty > 0) {

fishTypes.forEach(fish => {

fish.difficulty = fish.difficulty / totalFishDifficulty;

});

}

Copilot · 2026-02-27T18:10:30Z

blackroad-pixel/games/index.html

+    <a href="pokemon/index.html" class="game-card creatures">
+      <div class="card-preview">
+        <div class="scene preview-creatures"></div>
+        <div class="card-icons">\u26A1\uD83D\uDD2E</div>
+        <span class="card-badge badge-rpg">PIXEL RPG</span>


This card-icons value uses \u.... escape sequences in HTML and will render as literal text rather than emoji/icons. Replace with actual emoji characters or HTML entities so the preview shows the intended icons.

Copilot · 2026-02-27T18:10:30Z

CLAUDE.md

+│   ├── cecilia.yaml             # Mac dev machine
+│   ├── lucidia.yaml             # Pi 5 + Hailo-8
+│   ├── octavia.yaml             # Pi 5 + Hailo-8
+│   ├── aria.yaml                # Pi 5 agent orchestration


nodes/ in the structure diagram omits nodes/arcadia.yaml, which exists in this repo. This makes the directory map inaccurate and could confuse automation/docs that rely on it; please update the listing to include Arcadia (and keep the node list in sync with nodes/).

Suggested change

│ ├── aria.yaml # Pi 5 agent orchestration

│ ├── aria.yaml # Pi 5 agent orchestration

│ ├── arcadia.yaml # Arcadia node configuration

Copilot · 2026-02-27T18:10:30Z

CLAUDE.md

+cd blackroad-pixel && python3 -m http.server 8080
+
+# Run a prototype
+cd prototypes/operator && python3 -m cli


The quick command cd prototypes/operator && python3 -m cli does not work in the current repo layout (there is no prototypes/operator/cli.py). The CLI entry point appears to be prototypes/operator/routing/cli.py, so the command should be updated (e.g. run the module under routing).

Suggested change

cd prototypes/operator && python3 -m cli

cd prototypes/operator && python3 -m routing.cli

Copilot · 2026-02-27T18:10:31Z

blackroad-pixel/games/pokemon/index.html

+function checkTrainerEncounter(){
+  trainers.forEach(t=>{
+    if(t.defeated) return;
+    const dist=Math.abs(player.x-t.x)+Math.abs(player.y-t.y);
+    if(dist<=2){
+      // Trigger trainer battle
+      const intro=document.getElementById('trainer-intro');
+      const introText=document.getElementById('trainer-intro-text');
+      introText.textContent=t.msg;
+      intro.style.display='flex';
+      setTimeout(()=>{
+        intro.style.display='none';
+        startBattle(t.party[0],true,t);
+      },2000);
+    }


checkTrainerEncounter() schedules a setTimeout every time the player is within distance <= 2 of a trainer, without changing state or tracking a pending intro. This can enqueue multiple timeouts (triggering multiple battles) and still allows the player to move away while the intro is showing. Add a guard (e.g. a trainerIntroActive / pendingTrainerBattle flag and/or store/clear the timeout) and transition to a non-overworld state during the intro.

Copilot · 2026-02-27T18:10:31Z

blackroad-pixel/games/index.html

+    <a href="webkinz/index.html" class="game-card pets">
+      <div class="card-preview">
+        <div class="scene preview-pets"></div>
+        <div class="card-icons">\uD83D\uDC31\uD83D\uDC36</div>
+        <span class="card-badge badge-sim">VIRTUAL PET</span>


This card-icons value uses \u.... escape sequences in HTML and will render as literal text rather than emoji/icons. Replace with actual emoji characters or HTML entities so the preview shows the intended icons.

Copilot · 2026-02-27T18:10:31Z

blackroad-pixel/games/index.html

+    <a href="mario/index.html" class="game-card runner">
+      <div class="card-preview">
+        <div class="scene preview-runner"></div>
+        <div class="card-icons">\uD83C\uDF1F\uD83C\uDF44</div>
+        <span class="card-badge badge-platform">PLATFORMER</span>


This card-icons value uses \u.... escape sequences in HTML and will render as literal text rather than emoji/icons. Replace with actual emoji characters or HTML entities so the preview shows the intended icons.

Copilot · 2026-02-27T18:10:31Z

blackroad-pixel/games/index.html

+    <a href="stardew/index.html" class="game-card harvest">
+      <div class="card-preview">
+        <div class="scene preview-harvest"></div>
+        <div class="card-icons">\uD83C\uDF3E\uD83C\uDFE1</div>
+        <span class="card-badge badge-farm">FARM SIM</span>


card-icons uses JavaScript-style Unicode escape sequences (e.g. \uD83C\uDF3E) in HTML text nodes, which will render literally instead of showing the intended emoji/icons. Use the actual emoji characters or HTML entities (e.g. 🌾) so the icons display correctly without JS processing.

claude added 4 commits February 3, 2026 23:39

Add Games nav link to desktop UI

75b232e

https://claude.ai/code/session_016tjFc6t2emynRTw5Mbi9Y9

github-advanced-security bot found potential problems Feb 4, 2026

View reviewed changes

blackboxprogramming requested a review from Copilot February 27, 2026 18:06

Copilot started reviewing on behalf of blackboxprogramming February 27, 2026 18:06 View session

blackboxprogramming marked this pull request as ready for review February 27, 2026 18:10

Copilot AI reviewed Feb 27, 2026

View reviewed changes

@@ -2036,7 +2036,7 @@
             function showBanner(text) {
               const banner = document.getElementById('level-banner');
-              banner.innerHTML = text.replace('\n', '<br>');
+              banner.innerHTML = text.replace(/\n/g, '<br>');
               banner.style.display = 'block';
               setTimeout(() => { banner.style.display = 'none'; }, 3000);
             }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add CLAUDE.md guide and pixel game hub launcher#21

Add CLAUDE.md guide and pixel game hub launcher#21
blackboxprogramming wants to merge 4 commits intomainfrom
claude/claude-md-ml782dkg5pxhk2xe-Zb6h7

blackboxprogramming commented Feb 4, 2026

Uh oh!

Check failure

Copilot Autofix

chatgpt-codex-connector bot commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

+// Normalize fish difficulties so they form a proper probability distribution
+const totalFishDifficulty = fishTypes.reduce((sum, fish) => sum + fish.difficulty, 0);
+if (totalFishDifficulty > 0) {
+  fishTypes.forEach(fish => {
+    fish.difficulty = fish.difficulty / totalFishDifficulty;
+  });
+}

	│ ├── aria.yaml # Pi 5 agent orchestration
	│ ├── aria.yaml # Pi 5 agent orchestration
	│ ├── arcadia.yaml # Arcadia node configuration

	cd prototypes/operator && python3 -m cli
	cd prototypes/operator && python3 -m routing.cli

Conversation

blackboxprogramming commented Feb 4, 2026

Summary

Key Changes

Implementation Details

Notes

Uh oh!

Check failure

Copilot Autofix

chatgpt-codex-connector bot commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants